api: Expose reference-vector helpers - #53

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

Merge-order note from #42 review: #42 introduces bech32.interpret_mixed_case as shared correction/CLI policy. It should not become part of the supported module API. Review/merge #42 before this PR; when resolving the bech32.py conflict here, preserve the private-name signal by carrying it as _interpret_mixed_case (and update internal imports), with no package-level codex32.__all__ export. This keeps #53’s stated API boundary consistent with the review nit on #42.

Review follow-up: the blank-line docstring nit is valid but non-functional. I’m leaving the current one-commit API diff intact until #42 and #57 land because #53 already has mechanical rename conflicts with both; remove the extra blank lines in that single conflict-refresh commit rather than creating another pre-conflict churn commit. Human review order: #42 and #57 before #53.

Second merge-order/API-boundary note from #13 review: after #13 lands, deduplicate the two ASCII-only case-fold implementations by adding one private bech32._ascii_lower and importing it from _cli_input.py and generation.py. Together with the earlier #42 note (interpret_mixed_case → private _interpret_mixed_case), this keeps both shared lexical/correction helpers intentionally private while #53 publishes only the documented reference-vector helpers.

Review-submission follow-up: ACK stands. The blank-line-after-docstring nit is style-only; handle it when this branch is refreshed after #13/#42 so the conflict resolution stays one mechanical API-boundary pass. That same refresh should (1) centralize private _ascii_lower, (2) keep mixed-case policy private as _interpret_mixed_case, and (3) preserve the intentionally supported module-level vector helpers without widening package __all__.

Release-gate sequencing note: keep this after #13, #42, and #57 because the current conflicts are mechanical renames. One concrete helper-boundary cleanup should be folded into this pass: #13 currently has equivalent ASCII-only lowercase helpers in generation.py and _cli_input.py; its review deliberately deferred centralizing them here. Use one private bech32._ascii_lower (or equivalent private common helper) and update both callers while preserving package-level codex32.__all__ at 24. Also address the existing docstring-spacing nit during the conflict refresh.

Final-refresh note: preserve the current ACKed public-vector API and ASCII-only behavior, then normalize the small docstring-spacing nit while replaying/squashing the follow-up after #13/#42/#57. No separate churn is needed on the stale stack for a cosmetic-only change.

Agent API-boundary review at current head 316ea11: the user-facing problem is addressed without flattening the internal namespace. Vector authors get supported non-underscored module APIs (chars_to_u5, u5_to_chars, checksum constants/types, and checksum-selection helpers), while package-level codex32.__all__ remains the narrow backup/recovery surface. The Unicode-lookalike follow-up correctly uses ASCII-only lowercasing. Remaining cross-module underscore imports are internal implementation couplings and are explicitly documented rather than exposed. git diff --check is clean and exact-head Python-package run 36377610761 succeeded. No current code-review blocker; do the planned single mechanical refresh after #7/#13/#33/#42/#45/#57/#46/#64 settle, then human-rewrite/squash the Codex-authored follow-up.